QuickTime 3 Reference
A path contour is a series of connected points. The contour can contain both straight lines and curves. Therefore, the geometric points that make up a path contour can be on-curve points or off-curve control points. QuickDraw GX defines the gxPath structure to encapsulate a path contour geometry:
struct gxPath {
long vectors;
long controlBits[gxAnyNumber];
struct gxPoint vector[gxAnyNumber];
};
The vectors field indicates the number of geometric points in the path and the vector array contains the geometric points themselves. The controlBits array specifies which geometric points are on-curve points and which are off-curve control points. A value of 0 indicates an on-curve point and a value of 1 indicates an off-curve point. For example, a controlBits field with the value
0x55555555 /* 0101 0101 0101 0101 ... */
indicates that every other point is an off-curve control point; the first point is on curve, the second point is off, and so on. As another example, a controlBits field value of
0x00000000 /* 0000 0000 0000 0000 ... */
indicates all points are on curve, which effectively creates a polygon.
Notice that the controlBits array allows you to specify sequential off-curve control points. For example, a controlBits value of
0xFFFFFFFF /* 1111 1111 1111 1111 ... */
indicates that all points are off curve. When you indicate that two control points in a row are off curve, QuickDraw GX assumes an on-curve point midway between them.
The path shape allows you to group any number of contours within a single QuickDraw GX shape. The gxPaths structure encapsulates the multiple-path geometry:
struct gxPaths {
long contours;
struct gxPath contour[gxAnyNumber];
};
The contours field indicates the total number of contours (in other words, the total number of separate paths), and the contour array contains the path geometries.
Since a gxPaths structure is of variable length and every element in it is of type long , you can define a path geometry as an array of long values.
The path shown in Figure 11 has four on-curve points and two off-curve points. When drawn with the open-frame shape fill, it contains two curves and one straight line.
For more information about shape fills, see "Shape Fill" .
The next example shows how you can create a path using only off-curve control points. The path defined in this example contains four control points, and the controlBits field is set to
0xF0000000 /* 1111 0000 0000 0000 0000 ... */
which indicates that the first four points are off curve. The path contains only four points, and therefore they are all off curve.
The four off-curve control points in this example form a square; the path that they define is a rounded square, as shown in Figure 12 .
Notice that the path is filled with the even-odd shape fill, which is the default for path shapes. You could, however, specify any shape fill for this path except the open-frame shape fill. The open-frame shape fill requires that the first and last points of the contour be on-curve points, and this path has no on-curve points.
The next example shows how a single path shape can contain more than one path contour. The path shape defined in this example includes the round path from the previous example as well as a second round path, entirely contained within the first.
This is shown in Figure 13 .
Figure 13 A path shape with two concentric clockwise contours and closed-frame shape fill
If you don't specify a shape fill, you get the shape fill from the default path shape, which is the even-odd shape fill. The path shape resulting from an even-odd shape fill is shown in Figure 14 .
Figure 14 A path shape with two concentric clockwise contours and even-odd shape fill
Notice that the even-odd shape fill causes the fill of the outer contour, but not the inner contour. However, if you specify the winding shape fill for this path, the resulting shape would appear as shown in Figure 15 .
Figure 15 A path shape with two concentric clockwise contours and winding shape fill
Unlike the even-odd shape fill, the winding shape fill causes QuickDraw GX to fill inner contours-- as long as the inner contour has the same contour direction as the outer contour . If the inner contour and the outer contour have opposite contour directions, neither the even-odd shape fill nor the winding shape fill will fill the inner contour.
For example, if you change the direction of the inner contour from the previous example by reversing the order of the second path's geometric points and set the shape fill to the closed-frame shape fill, the resulting shape has contours with opposite contour directions, as depicted in Figure 16 .
Figure 16 Internal counterclockwise contour and closed-frame shape fill
Since the outer contour and the inner contour have opposite contour directions, neither the even-odd shape fill nor the winding shape fill cause QuickDraw GX to fill the inner contour, as shown in Figure 17 .
Figure 17 A path shape with even-odd or winding shape fill
